\chapter{库（Libraries）}
\label{librarychapter}
\mainindex{library，库}
库是一个程序可以被独立发布的部分。库系统支持库内的宏定义，宏导出，且区别需要定义和导出的不同阶段。本章为库定义了符号，且为库的扩展（expansion ）和执行定义了语义。

\section{库形式}
\label{librarysyntaxsection}

一个库定义必须有下面的形式：\mainschindex{library，库}\mainschindex{import}\mainschindex{export}

\begin{scheme}
(library \hyper{library~name}
  (export \hyper{export~spec} \ldots)
  (import \hyper{import~spec} \ldots)
  \hyper{library~body})%
\end{scheme}

一个库的声明包含下面的要素：

\begin{itemize}
\item \hyper{library~name}指定了库的名字（可能还有版本）。
\item {\cf export}子形式指定一个导出的列表，这个列表命名了定义在或导入到这个库的绑定的子集。
\item {\cf import}子形式指定了作为一个导入依赖列表导入的绑定，其中每一个依赖指定：
\begin{itemize}
\item 导入的库的名字，且可以可选地包含它的版本，
\item 相应的级别，比如，扩展（expand）或运行时（run time）（见\ref{phasessection}小节）和
\item 为了在导入库中可用的库导出的子集，和为在导入库中可用的为每一个库导出准备的名字。
\end{itemize}
\item \hyper{library body}是库的内部，由一系列定义和紧随其后的表达式组成。标识符可以既是本地的（未导出的）也是导出绑定的，且表达式是为它们的效果求值的初始化表达式。
\end{itemize}

一个标识符可以从两个或更多的库中使用相同的本地名字导入，或者使用两个不同的级别从相同的库中导入，只要每个库导出的绑定是一样的（也就是说，绑定在一个库中被定义，它只能通过导出和再导出经过导入）。否则，没有标识符可以被导入多次，被定义多次，或者同时被定义和导入。除了被显式地导入到库中或在库中定义的标识符，其它标识符在库中都是不可见的。

一个\hyper{library name}在一个实现中唯一地标识一个库，且在实现中的其它所有的库的{\cf import}子句（clauses）（见下面）中是全局可见的。一个\hyper{library name}有下面的形式：

\begin{scheme}
(\hyperi{identifier} \hyperii{identifier} \ldots \hyper{version})%
\end{scheme}

其中\hyper{version}或者是空的，或者有以下的形式：
%
\begin{scheme}
(\hyper{sub-version} \ldots)%
\end{scheme}

每一个\hyper{sub-version}必须表示一个精确的非负整数对象。一个空的\hyper{version}等价于{\cf ()}。

一个\hyper{export~spec}命名一个集合，这个集合包含导入的和本地的定义，这个集合将被导出，可能还会使用不同的外部名字。一个\hyper{export~spec}必须是如下的形式当中的一个：

\begin{scheme}
\hyper{identifier}
(rename (\hyperi{identifier} \hyperii{identifier}) \ldots)%
\end{scheme}

在一个\hyper{export~spec}中，一个\hyper{identifier}命名一个被定义在或被导入到库中的单独的绑定，其中，这个导入的外部名字和库中绑定的名字是一样的。一个{\cf rename}指明在每一个{\cf (\hyperi{identifier} \hyperii{identifier})}这样的配对中，被命名为\hyperi{identifier}的绑定使用\hyperii{identifier}作为外部名字。

每一个\hyper{import~spec}指定一个被导入到库中的绑定的集合，在这个集合中，级别是可见的，且通过它可以知道本地的名字。一个\hyper{import spec}必须是下面的一个：
%
\begin{scheme}
\hyper{import set}
(for \hyper{import~set} \hyper{import~level} \ldots)%
\end{scheme}

一个\hyper{import level}是下面中的一个：
\begin{scheme}
run
expand
(meta \hyper{level})%
\end{scheme}

其中\hyper{level}表示一个精确的整数对象。

在一个\hyper{import level}中，{\cf run}是{\cf (meta 0)}的缩写，且{\cf expand}是{\cf (meta 1)}的缩写。级别和阶段（phases）在\ref{phasessection}小节讨论。

一个\hyper{import~set}命名一个来自另一个库的绑定的集合，且可能为导入的绑定指定一个本地的名字。它必须是下面的一个：

\begin{scheme}
\hyper{library~reference}
(library \hyper{library~reference})
(only \hyper{import~set} \hyper{identifier} \ldots)
(except \hyper{import~set} \hyper{identifier} \ldots)
(prefix \hyper{import~set} \hyper{identifier})
(rename \hyper{import~set} (\hyperi{identifier} \hyperii{identifier}) \ldots)%
\end{scheme}

一个\hyper{library~reference}通过它的名字和可选的版本标识一个库。它有下面形式中的一个：

\begin{scheme}
(\hyperi{identifier} \hyperii{identifier} \ldots)
(\hyperi{identifier} \hyperii{identifier} \ldots \hyper{version~reference})%
\end{scheme}

一个第一个\hyper{identifier}是{\cf for}, {\cf library}, {\cf only}, {\cf except}, {\cf prefix}，或{\cf rename}的\hyper{library~reference}只允许出现在一个{\cf library \hyper{import~set}}中。否则{\cf <import set> (library <library reference>)}等价于\hyper{library~reference}。

一个没有\hyper{version~reference}（上面的第一个形式）的\hyper{library~reference}等价于\hyper{version~reference}是{\cf ()}的\hyper{library~reference}。

一个\hyper{version~reference}指定它匹配的\hyper{version}的一个子集。\hyper{library~reference}指定所有相同名字且版本匹配\hyper{version~reference}的库。一个\hyper{version~reference}有下面的形式：
%
\begin{scheme}
(\hyperi{sub-version reference} \ldots \hypern{sub-version reference})
(and \hyper{version reference} \ldots)
(or \hyper{version reference} \ldots)
(not \hyper{version reference})%
\end{scheme}
%
第一个形式的一个\hyper{version reference}匹配\hyper{version}至少$n$个要素的，且\hyper{sub-version reference}匹配对应的\hyper{sub-version}。一个{\cf and} \hyper{version reference}匹配一个版本，如果所有的跟在{\cf and}后的\hyper{version references}都匹配的话。相应地，{\cf or} \hyper{version reference}匹配一个版本，如果跟在{\cf or}后的一个\hyper{version reference}匹配的话。一个{\cf not} \hyper{version reference}匹配一个版本，如果跟在其后的\hyper{version reference}都不匹配的话。

一个\hyper{sub-version reference}有下列形式之一：

\begin{scheme}
\hyper{sub-version}
(>= \hyper{sub-version})
(<= \hyper{sub-version})
(and \hyper{sub-version~reference} \ldots)
(or \hyper{sub-version~reference} \ldots)
(not \hyper{sub-version~reference})%
\end{scheme}

第一个形式的一个\hyper{sub-version reference}匹配一个版本，如果二者相等。第一个形式的{\cf >=} \hyper{sub-version reference}匹配一个子版本如果它大于等于跟在它后面的\hyper{sub-version}；{\cf <=}与其类似。一个{\cf and} \hyper{sub-version reference}匹配一个子版本，如果所有随后的\hyper{sub-version reference}都匹配的话。相应地，一个{\cf or} \hyper{sub-version reference}匹配一个子版本，如果随后的\hyper{sub-version reference}中的一个匹配的话。一个{\cf not} \hyper{sub-version reference}匹配一个子版本，如果随后的\hyper{sub-version reference}都不匹配的话。

例子：

\texonly\begin{center}\endtexonly
  \begin{tabular}{lll}
    版本参考 & 版本 & 匹配？
    \\
    {\cf ()} & {\cf (1)} & 是\\
    {\cf (1)} & {\cf (1)} & 是\\
    {\cf (1)} & {\cf (2)} & 否\\
    {\cf (2 3)} & {\cf (2)} & 否\\
    {\cf (2 3)} & {\cf (2 3)} & 是\\
    {\cf (2 3)} & {\cf (2 3 5)} & 是\\
    {\cf (or (1 (>= 1)) (2))} & {\cf (2)} & 是\\
    {\cf (or (1 (>= 1)) (2))} & {\cf (1 1)} & 是\\
    {\cf (or (1 (>= 1)) (2))} & {\cf (1 0)} & 否\\
    {\cf ((or 1 2 3))} & {\cf (1)} & 是\\
    {\cf ((or 1 2 3))} & {\cf (2)} & 是\\
    {\cf ((or 1 2 3))} & {\cf (3)} & 是\\
    {\cf ((or 1 2 3))} & {\cf (4)} & 否
  \end{tabular}
\texonly\end{center}\endtexonly

当多于一个库被库参考引用的时候，库的选择有实现定义的方法决定。

为了避免诸如不兼容的类型和重复的状态这些问题，实现必须禁止库名字由相同标识符序列组成但版本不匹配的两个库在同一个程序中共存。

默认情况下，一个被导入的库导出的所有的绑定在一个使用被导入的库给的绑定的名字的导入库中是可见的。被导入的绑定和那些绑定的名字的精确的集合可以通过下面描述的{\cf only}, {\cf except}, {\cf prefix}, 和{\cf rename}形式进行调整。

\begin{itemize}
\item 一个{\cf only}形式产生来自另一个\hyper{import~set}的绑定的一个子集，只包括被列出的\hyper{identifier}。被包含的\hyper{identifier}必须在原始的\hyper{import~set}中。
\item 一个{\cf except}形式产生来自另一个\hyper{import~set}的绑定的一个子集，包括除了被列出的所有的\hyper{identifier}。所有被排除的\hyper{identifier}必须在原始的\hyper{import~set}中。
\item 一个{\cf prefix}从另一个\hyper{import~set}中添加一个\hyper{identifier}前缀到每个名字中。
\item 一个{\cf rename}形式，{\cf (rename (\hyperi{identifier} \hyperii{identifier}) \ldots)}，从一个中间的\hyper{import~set}删除{\cf \hyperi{identifier} \ldots}的绑定，然后将对应的{\cf \hyperii{identifier} \ldots}添加回到最终的\hyper{import~set}中。每一个\hyperi{identifier}必须在原始的\hyper{import~set}中，每一个\hyperii{identifier}必须不在中间的\hyper{import~set}中，且\hyperii{identifier}必须是不一样的。
\end{itemize}
不符合上面的约束是一个语法错误。

\label{librarybodysection}
一个{\cf 库}形式的\hyper{library~body}由被分类为\textit{定义（definitions）}\mainindex{definition，定义}或\textit{表达式（expressions）}\mainindex{expression，表达式}的形式组成。哪些形式属于哪些类型是根据被导入的库和表达式的结果来决定的---见第\ref{expansionchapter}章。通常，不是定义（见\ref{defines}小节，有基本库可见的定义）的形式是表达式。

一个\hyper{library~body}和\hyper{body}差不多（见\ref{bodiessection}小节），除了一个\hyper{library~body}不需要包括任何表达式。它必须有下面的形式：

\begin{scheme}
\hyper{definition} \ldots \hyper{expression} \ldots%
\end{scheme}

当{\cf begin}, {\cf let-syntax}, 或{\cf letrec-syntax}形式先于第一个表达式出现在顶层内部的时候，它们被拼接成内部；见\ref{begin}小节。内部的一些或所以，包括在{\cf begin}, {\cf let-syntax}, 或{\cf letrec-syntax}形式里面的部分，可以通过一个句法抽象指定（见\ref{macrosection}小节）。

转换表达式和绑定像第\ref{expansionchapter}章描述的，按从左向右的顺序被求值和被创建。变量的表达式按从左向右求值，就像在一个隐式的{\cf letrec*}中，且内部的表达式也在变量定义的表达式之后从左向右进行求值。每一个导出的变量和它本地副本值得初始化都会创建一个新的位置。两次返回给内部最后表达式的继续的行为是未定义的。

\begin{note}
出现在库语法的名字{\cf library}，\allowbreak{}{\cf export}，\allowbreak{}{\cf import},
{\cf for}，\allowbreak{}{\cf run}，\allowbreak{}{\cf expand}，\allowbreak{}{\cf meta},
{\cf import}，\allowbreak{}{\cf export}，\allowbreak{}{\cf only}，\allowbreak{}{\cf except}，\allowbreak{}{\cf
  prefix}，\allowbreak{}{\cf rename}，\allowbreak{}{\cf and}，\allowbreak{}{\cf or}，\allowbreak{}{\cf not}，\allowbreak{}{\cf >=}\allowbreak{}和\allowbreak{}{\cf <=}\allowbreak{}
是语法的一部分，且不是被保留的，也就是说，相同的名字可以在库中用作其它的用途，甚至以不同的含义导出或导入到其它库中，这些都不会影响它们在{\cf 库}形式中的使用。
\end{note}

在一个库的里面定义的绑定在库外面的代码中是不可见的，除非绑定被显式地从这个库中导出。可是，一个导出的宏可能\emph{隐式地导出（implicitly export）}一个另外的标识符，其是在库中定义的或导入到库中的。也就是说，它可以插入标识符的一个引用到其产生的代码中。

\label{importsareimmutablesection}
所有的显式地导出的变量在导出的和导入的的库中都是不可变的。因此，不管是在导入的还是导出的库中，一个显式地导出的变量出现在一个{\cf set!}表达式的左边是一个语法错误。

所有的隐式地导出的变量在导出的和导入的的库中也都是不可变的。因此，在一个变量被定义的库的外面通过宏产生的代码中，如果这个变量出现在一个{\cf set!}表达式的左边，那么这是一个语法错误。如果一个被赋值的变量的引用出现在这个变量被定义的库的外面通过宏产生的代码中，那么这也是一个语法错误，其中，一个被赋值的变量指出现在导出库中一个{\cf set!}表达式左边的变量。

所有其它的定义在一个库中的变量是可变的。

\section{导入和导出级别（levels）}
\label{phasessection}

扩展一个库可能需要来自其它库的运行时信息。比如，如果一个宏转换调用一个来自库$A$的过程，那么在库$B$中扩展宏的任何使用之前，库$A$必须被实例化（instantiated）。当库$B$作为一个程序的部分被最终运行的时候，库$A$可能不被需要，或者，它可能也被库$B$的运行时需要。库机制使用阶段来区别这些时间，这会在本小节解释。

每个库可用通过扩展时（expand-time）信息（最低限度地，它的导入的库，导出的关键词的一个列表，导出的变量的一个列表，计算转换表达式的代码）和运行时信息（最低限度地，计算变量定义的右边表达式的代码，计算内部表达式的代码）表现其特征。扩展时信息必须对任何导出绑定的扩展引用可见，且运行时信息必须对任何导出变量绑定的求值引用可见。

\mainindex{phase，阶段B}
%
一个\emph{阶段（phase）}是一段时间，在这段时间里库中的表达式被求值。在一个库的内部，顶层表达式和{\cf define}形式的右边在运行时，也就是阶段$0$，被求值，且{\cf define-syntax}形式的右边在扩展时，也就是阶段$1$，被求值。当{\cf define-syntax}, {\cf let-syntax}, 或{\cf letrec-syntax}出现在在阶段*n*被求值的代码中时，它们的右边将在阶段$n+1$被求值。

这些阶段和库它自己使用的阶段是相关的。库的一个\defining{实例（instance）}对应于一个与另一个库相关的特定阶段的它的变量定义和表达式的求值过程---一个叫做\defining{实例化（instantiation）}的过程。比如，如果库$B$中的一个顶层表达式引用库$A$中导出的一个变量，那么它在阶段$0$（相对于$B$的阶段）从$A$的一个实例中引用这个导出。但是，$B$中一个阶段$1$的表达式引用$A$中相同的绑定，那么，它在阶段$1$（相对于$B$的阶段）从$A$的一个实例中引用这个导出。

一个库的\defining{访问（visit）}对应于在一个特定阶段与另一个库相关的语法定义的计算过程—一个叫做\defining{访问（visit）}的过程。比如，如果库$B$中的一个顶层表达式引用来库$A$导出的一个宏，那么，它在阶段$0$（相对应$B$的阶段）从$A$的访问中引用这个导出，其对应于在阶段$1$宏转换表达式的求职过程。

\mainindex{level}\mainindex{import level}
%
一个\emph{级别}是一个标识符的词法属性，其决定了它可以在哪个阶段被引用。在一个库中，每个用定义绑定的标识符的级别是$0$；也就是说，在库中只能在阶段$0$引用这个标识符。除了导出库中标识符的级别之外，每一个导入的绑定的级别由导入库中{\cf import}的封装的{\cf for}形式决定。导入和导出级别通过所有级别组合的成对相加的方式组合。比如，一个以$p_a$和$p_b$级别导出，以$q_a$，$q_b$和$q_c$级别导入的被导入的标识符的引用在以下级别是有效的：$p_a + q_a$, $p_a + q_b$, $p_a + q_c$, $p_b + q_a$, $p_b + q_b$, 和$p_b + q_c$。一个没有封装的{\cf for}的\hyper{import~set}等价于{\cf (for \hyper{import~set} run)}，它和{\cf (for \hyper{import~set} (meta 0))}是一样的。

对于所有的定义在导出库中的绑定来说，一个被导出的的绑定的级别是$0$。一个重新导出的绑带，也就是一个从其它库导入的导出，的级别和重新导出库中的绑定的有效导入级别是一样的。

对于定义在库报告中的库来说，几乎所有的绑定，导出级别是$0$。例外是来自\rsixlibrary{base}库的{\cf syntax-rules}，\allowbreak{}{\cf identifier-syntax}，\allowbreak{}{\cf ...}\allowbreak{}和\allowbreak{}{\cf \_}\allowbreak{}形式以级别$1$被导出，来自\rsixlibrary{base}库的{\cf set!}形式以级别$0$和$1$被导出，来自复合\thersixlibrary{}库（见库的第\extref{lib:complibchapter}{Composite library}章）的所有绑定以级别$0$和$1$被导出。

一个库中的宏扩展可以引出标识符的一个引用，其中这个标识符没有显式地导入到这个库中。在这种情况下，引用的阶段必须符合标识符的作为偏移的级别，这个偏移是源库（也就是提供标识符词法上下文的库）和封装引用的库的阶段的不同。比如，假设扩展一个库调用一个宏转换，且宏转换的求值引用一个标识符，这个标识符被从另一个库中被导出（所以，库的阶段$1$的实例被使用）；进一步假设绑定的值是一个表示一个指示级别$n$绑定的标识符的语法对象；那么，在库被扩展的时候，标识符必须只能在$n+1$阶段被使用。这个级别和阶段的组合就是为什么标识符负的级别是有用的，甚至，尽管库只存在非负的阶段。

如果在一个程序的扩展形式中，一个库的定义中的任何一个在阶段$0$被引用，那么被引用的库的一个作为阶段$0$实例会在程序的定义和表达式被求值之前被创建。这条规则的应用是透明的：如果一个库的扩展形式在阶段$0$从另一个库引用一个标识符，那么，在引用库在阶段$n$被实例化之前，被引用的库必须在阶段$n$被实例化。当一个标识符在任何大于$0$的阶段$n$被引用，那么于此相反，定义库会在阶段$n$被实例化，其在引用被求值之前的一些未定义的时间。同样地，在一个库的扩展期间，当一个宏关键词在阶段$n$被引用的时候，定义库在阶段$n$被访问，其是引用被计算之前的一定未定义的时间。

一个实现可以为不同的阶段区别实例/访问，或者在任何阶段使用一个实例/访问就像在任何其它阶段的一个实例/访问一样。更进一步，一个实现可以扩展每一个{\cf 库}形式以区别在任何阶段的库的访问和/或在大于$0$的阶段的库的实例。一个实现可以创建更多库的实例/访问在比要求的安全引用的更多的阶段。当一个标识符作为一个表达式出现在一个与标识符级别不一致的阶段时，那么一个实现可以抛出一个异常，异常的抛出可以在扩展时也可以在运行时，或者，它也可以允许这个引用。因此，一个库可能是不可移植的，当其含义依赖于一个库的实例在库的整个阶段或{\cf library}扩展时是有区别的还是共享的时候。

\section{例子}

各种\hyper{import~spec}和\hyper{export~spec}的例子：

（注：下面的例子已根据勘误表更正。）

\begin{scheme}
(library (stack)
  (export make push! pop! empty!)
  (import (rnrs)
          (rnrs mutable-pairs))

  (define (make) (list '()))
  (define (push! s v) (set-car! s (cons v (car s))))
  (define (pop! s) (let ([v (caar s)])
                     (set-car! s (cdar s))
                     v))
  (define (empty! s) (set-car! s '())))

(library (balloons)
  (export make push pop)
  (import (rnrs))

  (define (make w h) (cons w h))
  (define (push b amt)
    (cons (- (car b) amt) (+ (cdr b) amt)))
  (define (pop b) (display "Boom! ")
                  (display (* (car b) (cdr b)))
                  (newline)))

(library (party)
  ;; 所有的导出:
  ;; make, push, push!, make-party, pop!
  (export (rename (balloon:make make)
                  (balloon:push push))
          push!
          make-party
          (rename (party-pop! pop!)))
  (import (rnrs)
          (only (stack) make push! pop!) ; 非空的！
          (prefix (balloons) balloon:))

  ;; 以气球的堆栈创建一个派对（party）,
  ;; 从两个气球开始
  (define (make-party)
    (let ([s (make)]) ; from stack
      (push! s (balloon:make 10 10))
      (push! s (balloon:make 12 9))
      s))
  (define (party-pop! p)
    (balloon:pop (pop! p))))


(library (main)
  (export)
  (import (rnrs) (party))

  (define p (make-party))
  (pop! p)        ; 显示"Boom! 108"
  (push! p (push (make 5 5) 1))
  (pop! p))       ; 显示"Boom! 24"%
\end{scheme}

宏和阶段的例子:

\begin{schemenoindent}
(library (my-helpers id-stuff)
  (export find-dup)
  (import (rnrs))

  (define (find-dup l)
    (and (pair? l)
         (let loop ((rest (cdr l)))
           (cond
            [(null? rest) (find-dup (cdr l))]
            [(bound-identifier=? (car l) (car rest))
             (car rest)]
            [else (loop (cdr rest))])))))

(library (my-helpers values-stuff)
  (export mvlet)
  (import (rnrs) (for (my-helpers id-stuff) expand))

  (define-syntax mvlet
    (lambda (stx)
      (syntax-case stx ()
        [(\_ [(id ...) expr] body0 body ...)
         (not (find-dup (syntax (id ...))))
         (syntax
           (call-with-values
               (lambda () expr)
             (lambda (id ...) body0 body ...)))]))))

(library (let-div)
  (export let-div)
  (import (rnrs)
          (my-helpers values-stuff)
          (rnrs r5rs))

  (define (quotient+remainder n d)
    (let ([q (quotient n d)])
      (values q (- n (* q d)))))
  (define-syntax let-div
    (syntax-rules ()
     [(\_ n d (q r) body0 body ...)
      (mvlet [(q r) (quotient+remainder n d)]
        body0 body ...)])))%
\end{schemenoindent}


%%% Local Variables:
%%% mode: latex
%%% TeX-master: "r6rs"
%%% End:
